home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / mus / play / multiplsr.lha / include / remind.h < prev    next >
C/C++ Source or Header  |  1992-09-14  |  5KB  |  113 lines
  1. /*
  2.  * BryLib - a mishmash of useful library routines
  3.  * Copyright (C) 1992 Bryan Ford
  4.  *
  5.  * This library is free software; you can redistribute it and/or
  6.  * modify it under the terms of the GNU Library General Public
  7.  * License as published by the Free Software Foundation; either
  8.  * version 2 of the License, or (at your option) any later version.
  9.  *
  10.  * This library is distributed in the hope that it will be useful,
  11.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  * Library General Public License for more details.
  14.  *
  15.  * You should have received a copy of the GNU Library General Public
  16.  * License along with this library; if not, write to the Free
  17.  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18.  *
  19.  * Reminder list handling
  20.  * $Id$
  21.  *
  22.  * $Log$
  23.  *
  24.  */
  25. #ifndef BRY_REMIND_H
  26. #define BRY_REMIND_H
  27.  
  28. #ifndef BRY_CLIST_H
  29. #include "bry/clist.h"
  30. #endif
  31.  
  32.  
  33. /* One of these structures "remembers" a function to be called later. */
  34. struct RemindNode
  35.   {
  36.     struct CNode node;                  /* Circular-list node */
  37.     long (*callfunc)(long globaldata,long localdata); /* What to call */
  38.     long localdata;
  39.     short sequence;                     /* Lower-sequence nodes get called first */
  40.     char inlist;                        /* Nonzero if this node is linked into a CallList */
  41.     char reserved;
  42.   };
  43.  
  44.  
  45. /* Handy macro to declare preinitialized instances of RemindNodes */
  46. #define remind_decl(name,func,seq) struct RemindNode name = {{0},func,seq}
  47.  
  48.  
  49. /* We don't need any fancy structures here--just a normal circular list. */
  50. #define RemindList        CList
  51.  
  52.  
  53. /* Initializing a CallList is also very simple. */
  54. #define remind_initlist(calllistptr) clist_init(calllistptr)
  55.  
  56.  
  57. /* Add a RemindNode to a RemindList.  Only adds if node->inlist is zero
  58.    (i.e. if the node is not already on the list).  Sets node->inlist to
  59.    nonzero.  This function keeps the list in order of sequence, so
  60.    when the list is traversed by one of the functions below the nodes
  61.    will be called in order from lowest sequence number to highest.
  62.    Nodes with the same sequence numbers are called in first-in, first-out
  63.    (i.e. first-added, first called) order.  */
  64. void remind_add(struct RemindList *list,struct RemindNode *node);
  65.  
  66.  
  67. /* Remove a RemindNode from a RemindList.  Only removes if node->inlist
  68.    is nonzero (i.e. if the node is on a list).  Sets node->inlist to zero.  */
  69. void remind_rem(struct RemindNode *node);
  70. #define remind_remove(node) remind_rem(node)
  71.  
  72.  
  73. /* Call all the nodes on a RemindList non-destructively (leaving the nodes
  74.    in place as it goes along).  Note that though this function does not
  75.    remove any nodes, the functions it calls through the RemindNodes may
  76.    remove their own nodes.  callfuncs must return 0 to keep going through
  77.    list; nonzero causes remind_call to stop and return that value
  78.    immediately.  Returns -1 if the list was empty; 0 if all nodes processed
  79.    successfully.
  80.  
  81.    While callfuncs may remove their own nodes (the nodes that were used
  82.    to call them), they may not remove any other nodes on the list being
  83.    traversed.  They may add new nodes to the list being traversed, but
  84.    whether or not that node will get called on this particular run is
  85.    unspecified.  */
  86. long remind_call(struct RemindList *l,long globaldata);
  87.  
  88.  
  89. /* Extension to remind_call: afterfunc is called after each callfunc is
  90.    called.  It is passed the return code of the callfunc that was just
  91.    called, and its return code is used in place of the callfunc's return
  92.    code to determine whether to keep going in the list or stop.  */
  93. long remind_callext(struct RemindList *l,long globaldata,
  94.   long (*afterfunc)(struct RemindNode *node,long retcode,long globaldata));
  95.  
  96.  
  97. /* Call the nodes on a RemindList destructively, removing each node as it
  98.    progresses.  Returncode conventions work the same way as remind_call. Each
  99.    node is removed before its callfunc is called, so callfuncs may add their
  100.    own nodes back onto the list; the node will be called again later during
  101.    this same traversal, according to sequence.  (Be careful not to create
  102.    infinite loops.)  For that matter, callfuncs can safely add or delete any
  103.    nodes (their own or others) from the list while inside a remind_callrem.  */
  104. long remind_callrem(struct RemindList *l,long globaldata);
  105.  
  106.  
  107. /* Variation of remind_callrem with the afterfunc feature; differences are
  108.    the same as with remind_callext.  */
  109. long remind_callremext(struct RemindList *l,long globaldata,
  110.   long (*afterfunc)(struct RemindNode *node,long retcode,long globaldata));
  111.  
  112.  
  113. #endif